Hi @dmsnell,

I understand the challenge you’re facing with WordPress’s documentation generation, and I appreciate you reaching out with this proposal.

That said, I have some concerns about merging this PR. The version you’re targeting is over 10 years old, and while I see the immediate need, I can’t confidently assess the impact of any changes on users still relying on it. Even minimal patches could introduce unexpected issues, and I won’t be able to provide support for any problems that arise from this version.

I want to be upfront: I won’t be making any further changes or patches to this old release. However, I’d be happy to discuss how we can help WordPress transition to a newer version of the library or explore alternative solutions that might work better in the long run. If you’re open to it, let’s talk about how we can move forward together.

Looking forward to your thoughts!

Thanks @jaapio — I figured it was a long shot, and no worries — we can always reference our fork.

There’s a bigger effort to port the documentation extraction to phpstan/phpdoc-parser, but I was simply trying to make the most effective fixes with the least amount of work. I am going to try and get the nikic/php-parser dependency up to 4x, but in my explorations there were a few bigger changes there.

The WordPress docs generation is build around subclassing the Reflector classes (for example, the file reflector. When I looked at updating Reflection it seemed that there was a hard backwards compatible break not easy to pass, and I think others came to the same conclusion leading to their work to explore phpstan/phpdoc-parser.

If you think we overlooked an easy upgrade path that would be awesome to learn. Thanks for taking the time to respond here; I know we all have more on our plates than we can chew, and the world is a crazy place right now.

Would you prefer I close this PR? I can merge it into my fork and get this out of your inbox.

Thanks for your understanding.

Maybe small step back in history will help.
I talked with Milana in the past about a collaboration between the WordPress and phpDocumentor team. Back then we were focused on other projects. But I did build a proof of concept using phpDocumentor.

I don't know where you want to go, but it might be worth it to have a look at this.

phpDocumentor/phpDocumentor#3067

The idea was that phpDocumentor could write an json output to file that could be read by a WordPress plugin to publish the information.

If you want to go with phpstan/parser that's fine with me. But I need to warn you, I had multiple problems regarding WordPress in ReflectionDocblock that were reported by WordPress developers. There is also the option of going to phpDocumentor/ReflectionDocblock. That library is still compatible with the implementation you are using now. The Missing part is what you would need to implement with the phpstan/parser as well.